Inside Macintosh: Open Transport /

Chapter 6 - Configuration Management / Configuration Management Reference

Functions / Getting Information About Ports

OTCreatePortRef

Creates a port reference that describes a port's hardware characteristics.

C INTERFACE

OTPortRef OTCreatePortRef (UInt8 busType, 
                           UInt16 devType,
                           UInt16 slot, 
                           UInt16 other);

C++ INTERFACES

None. C++ applications use the C interface to this function.

PARAMETERS

busType

The type of bus to which the hardware port is connected; for example, a NuBus or PCI bus. See "The Port Reference" (page 6-19) for possible values for this parameter.

devType

The type of hardware device connected to the port, such as LocalTalk or Ethernet. See "The Port Reference" (page 6-19) for possible values for this parameter.

slot

The number of the physical slot containing the device.

other

The port's multiport identifier--that is, a numeric value that distinguishes between ports when more than one hardware port is connected to a given slot.

DESCRIPTION

The OTCreatePortRef function creates a port reference structure, which is a 32-bit value that describes a port's hardware characteristics: its device and bus type, its physical slot number, and, where applicable, its multiport identifie. Once you have created a port reference, you can use the OTFindPortByRef function to find a specific port with that particular set of characteristics.

To create a port reference, you use the OTCreatePortRef function. You must know all the port's hardware characteristics: its device and bus type, its slot number, and its multiport identifier (if it has one). You cannot use wildcards to fill in any element you don't know, although you can use a device type of 0 to allow matches on every kind of device type (following the zero-matches-everything rule). Possible device and bus types are described in the section "The Port Reference" (page 6-19).

To create a port reference for a pseudodevice, use 0 as the value for the
bus type, slot number, and multiport identifier, and use the constant kOTPseudoDevice for the device type.

Open Transport has predefined variants of the OTCreatePortRef function for the most commonly used hardware devices, such as the NuBus, PCI, and PCMCIA devices. These three variants are listed here:

#define OTCreateNuBusPortRef(devType, slot, other)\
      OTCreatePortRef(kOTNuBus, devType, slot, other)
#define OTCreatePCIPortRef(devType, slot, other)\
      OTCreatePortRef(kOTPCIBus, devType, slot, other)
#define OTCreatePCMCIAPortRef(devType, slot, other)\
      OTCreatePortRef(kOTPCMCIABus, devType, slot, other)

Once you have identified the port structure you want, you can access the information in its port reference, by using the OTGetDeviceTypeFromPortRef, OTGetBusTypeFromPortRef, and OTGetSlotFromPortRef functions.

SPECIAL CONSIDERATIONS

The slot numbers are physical; that is, they are the slot numbers returned by the Slot Manager and not the slots seen in various network configuration applications. Physical slot numbers depend on the type of card installed. For example, NuBus cards number their slots 9-13, which appear in the AppleTalk or TCP control panels as slots 1-5.

SEE ALSO

For information about finding ports and obtaining a port reference, see the sections "About Port Information" (page 6-5) and "Obtaining Port Information" (page 6-11).

See "The Port Reference" (page 6-19) for possible values for the bus type and device type.

To extract information from a port reference, use the OTGetDeviceTypeFromPortRef function (page 6-38),the OTGetBusTypeFromPortRef function (page 6-39), and the OTGetSlotFromPortRef function (page 6-40).

The port structure is described in "The Port Structure" (page 6-17).